<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" type="text/css" href="doc.css" />
<title>Sharing Transactions with Other Threads</title>
</head>
<body>
<h1><a name="top">Sharing Transactions with Other Threads</a></h1>
<p>
<a href="../javadoc/org/eclipse/emf/transaction/Transaction.html"><em class="CodeName">Transaction</em></a>s
are owned by threads.  The initial owner of a transaction is the thread in which context
it was created.  For the duration of a transaction, the owner thread has exclusive access
to the contents of the editing domain's resource set, except as described below.  The EMF
Transaction API provides two mechanisms for multiple threads to cooperatively share access
to the resource set:  yielding and privileged runnables.  Both of these mechanisms do, however,
maintain the single-threaded model of EMF by ensuring that only one thread at a time is
ever reading or writing.
</p>

<h2>Yielding Read-only Transactions</h2>

<p>
Some read-only operations are typically long-running, such as validation (perhaps using the
EMF Validation Framework) or searching (perhaps using the EMF Model Query framework).  For
these kinds of operations, Eclipse provides such facilities as the Jobs API and progress
monitors to do work in the background and/or keep the user abreast of what is happening.
</p><p>
Because transactions in a <em class="CodeName">TransactionalEditingDomain</em> lock the
resource set for exclusive access by a single thread, a read-only transaction that runs for
a long time can severely impair the responsiveness of an application's UI if refreshes
require reading the EMF data.
</p><p>
To address these situations, the
<a href="../javadoc/org/eclipse/emf/transaction/TransactionalEditingDomain.html"><em class="CodeName">TransactionalEditingDomain</em></a>
provides a <em class="CodeName">yield()</em> method that suspends the current transaction to
allow the next thread waiting for a read-only transaction to start, if there is any such
thread waiting.  Only read-only transactions may be yielded in this way, because yielding
any transaction to a writer would result in the data that a reader has already read being
changed, so that when the reader resumes later, its assumptions about the data are invalid.
This phenomenon is known as a "dirty read."
</p>
<pre class="Code">
final TransactionalEditingDomain domain;
final IProgressMonitor monitor;

// acquire read transaction on this thread
domain.<b>runExclusive</b>(new Runnable() {
    public void run() {
        while (moreToRead()) {
            // ... do a bunch of reading ...
            readSomeStuff();

            // checking the progress monitor is a good opportunity to
            //    yield to other readers
            if (monitor.<b>isCancelled</b>()) {
                forgetIt();
                break;
            }
            
            domain.<b>yield</b>(); // just returns if no readers waiting 
        }
    }});
</pre>
<p>
Read access may be yielded to a thread that is waiting to start a read-only transaction or
to a thread that has a read action in progress that is currently suspended on a yield,
waiting to resume it.  Yielding proceeds in round-robin fashion amongst the
set of threads currently waiting for or suspending read-only transactions; there is no
facility for prioritization of threads.  Any thread
wishing to start a read/write transaction must wait until all active read-only transactions
have completed.
</p><p>
A practical rule of thumb for deciding when to yield a read transaction is to do it whenever
checking a progress monitor for cancellation and/or updating the progress.
</p>

<h2>Sharing Read/Write Transactions</h2>

<p>
We have seen how multiple threads with read-only transactions can take turns reading by
cooperatively yielding (suspending) their transactions.  It is, however, common in Eclipse
for a thread to be required to synchronously communicate with another thread in order
to accomplish some task.
</p><p>
Probably the most common occurrence of this is in the updating
of UI widgets from background threads or jobs.  The SWT API requires that all modifications
to widgets be performed on a thread designated as the <em class="CodeName">Display</em>
thread.  What does a thread do if it has a read/write transaction in progress and it
needs to execute code on the UI thread in a <em class="CodeName">Display.syncExec()</em>
call, and this synchronous runnable might need to read the resource set or even modify it?
</p><p>
The thread that owns a transaction can use the
<em class="CodeName">TransactionalEditingDomain.createPrivilegedRunnable(Runnable)</em>
method to wrap an operation (encapsulated in a <em class="CodeName">Runnable</em>) in a
<em>privileged runnable</em>.  This privileged runnable, when executed on some other thread,
borrows the original owning thread's transaction for the duration of its execution, which
it delegates to the wrapped runnable.  This is ideal for use with APIs such as
<em class="CodeName">Display.syncExec()</em>, in which the thread that lends its transaction
(via the privileged runnable) to the display thread waits for the display thread to finish
executing the runnable before resuming.
</p>
<p class="Note">
Privileged runnables can only be used with synchronous inter-thread communication mechanisms
such as <em class="CodeName">Display.syncExec()</em>.  Attempting asynchronous runnables
(as with <em class="CodeName">Display.asyncExec()</em>) will certainly lead to an illegal
transaction state.  A thread that posts an asynchronous invocation of a privileged runnable
will proceed with reading and modifying the resource set, only to find suddenly that it
no longers owns the transaction because the other thread has taken it over.
</p>

<pre class="Code">
TransactionalEditingDomain domain;
final org.eclipse.swt.widgets.List bookList;

// acquire read transaction on this thread
domain.<b>runExclusive</b>(new Runnable() {
    public void run() {
        // hand it off to the UI thread to read the library and update
        //    the list widget
        Display.<b>syncExec</b>(domain.<b>createPrivilegedRunnable</b>(
            new Runnable() {
                public void run() {
                    // the UI thread now has the transaction to read the resource set
                    List&lt;String&gt; bookTitles = new ArrayList&lt;String&gt;();            
                    for (Book book : library.getBooks) {
                        bookTitles.add(book.getTitle());
                    }
                    
                    // update the UI
                    bookList.<b>setItems</b>(bookTitles.toArray(new String[bookTitle.size()]));
                }   // the UI thread gives up the transaction
            }));
</pre>
<p>
Of course, a real application probably would not directly nest runnables in this way.
The code that interacts with the UI thread would more likely be indirectly invoked by a
<em class="CodeName">runExclusive()</em> runnable through some possibly deep call stack.
</p><p>
This mechanism works with both read-only and read/write transactions because only a single
transaction is involved.  The privileged runnable differs from yield in being directed at a
specific other thread, which then returns the transaction directly back to the original
owner.  We do not have multiple independent threads creating transactions for their own
purposes, but rather a thread that deliberately continues a synchronous operation on
another thread during some interval.
</p><p>
Note that a thread executing a privileged runnable can, in turn, lend the transaction to
yet another thread via another privileged runnable.  This can be repeated an arbitrary
number of times, even cycling back to a thread that is already lending the transaction
away in a privileged runnable.
</p>


<hr/>

<p>
<a href="https://www.eclipse.org/legal/epl-2.0/">Copyright (c) 2006, 2007 IBM Corporation and others.</a>
</p>
</body>
</html>
